<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" type="text/css" href="doc.css" />
<title>The Resource Undo Context</title>
</head>
<body>
<h1><a name="top">The Resource Undo Context</a></h1>
<p>
One of the advantages of the Eclipse Operation History API is its ability to implement a
not-exactly-linear undo model, in which different operations executed on the same history
are only partially or not at all ordered, according to whether their contexts are
dependent.  The <em class="CodeName">IUndoContext</em> API effectively implements multiple
undo "stacks" in a single history.
</p><p>
The workspace editing domain API provides a
<a href="../javadoc/org/eclipse/emf/workspace/ResourceUndoContext.html"><em class="CodeName">ResourceUndoContext</em></a>
that tags EMF operations with the <em class="CodeName">Resource</em>s in the resource set
that they affect.  Thus, in a single editing domain (on a single operation history), editors
on different resources can maintain separate undo stacks on the <em class="UILabel">Edit</em>
menu.  Operations that affect multiple resources will appear in the <em class="UILabel">Undo</em>
menu action for multiple editors.  Operations that affect only a single resource will not.
</p>

<blockquote>
	<img src="images/undocontext.png" alt="Resource Undo Context API"/><br/>
	<font size="-2">[<a href="images/undocontext.svg">as SVG</a>]</font>
</blockquote>

<p>
The <em class="CodeName">IWorkspaceCommandStack</em> listens to the execution of operations
on its <em class="CodeName">IOperationHistory</em> and automatically appends
<em class="CodeName">ResourceUndoContext</em>s for each resource affected by an operation.
It determines affected resources by analysis of <em class="CodeName">Notification</em>s,
using the following rules:
</p>
<ul>
   <li>the resource containing the notifier of a notification is, obviously, affected</li>
   <li>in the case of a change to an <em class="CodeName">EReference</em>, the resources
       containing any objects added to or removed from the reference value are affected.
       This holds for bidirectional references (having <em class="CodeName">eOpposites</em>)
       and for unidirectional references, in the latter case because the API assumes that
       there may be some implicit or derived dependency in the opposite direction</li>
</ul>
<p>
Clients can use the <em class="CodeName">ResourceUndoContext.getAffectedResources(List)</em>
API to compute the resources affected by a transaction themselves, if they are not using
a workspace command stack on their operation history.
</p><p>
An editor that uses a resource context as its editor context will populate its undo and
redo menus with operations that affected its resource.  The
<a href="../examples/workspaceExample.html">workspace-integrated editor example</a>
demonstrates exactly this.
</p>

<hr/>

<p>
<a href="https://www.eclipse.org/legal/epl-2.0/">Copyright (c) 2006, 2007 IBM Corporation and others.</a>
</p>
</body>
</html>
